<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="ctypes-passing-pointers.html" />
<link rel="prev" href="ctypes-specifying-required-argument-types.html" />
<link rel="parent" href="ctypes-ctypes-tutorial.html" />
<link rel="next" href="ctypes-passing-pointers.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>14.14.1.8 Return types</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="14.14.1.7 specifying the required"
  href="ctypes-specifying-required-argument-types.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="14.14.1 ctypes tutorial"
  href="ctypes-ctypes-tutorial.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="14.14.1.9 passing pointers (or:"
  href="ctypes-passing-pointers.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="ctypes-specifying-required-argument-types.html">14.14.1.7 Specifying the required</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="ctypes-ctypes-tutorial.html">14.14.1 ctypes tutorial</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="ctypes-passing-pointers.html">14.14.1.9 Passing pointers (or:</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h3><a name="SECTION00161418000000000000000"></a><a name="ctypes-return-types"></a>
<br>
14.14.1.8 Return types
</h3>

<p>
By default functions are assumed to return the C <code>int</code> type.  Other
return types can be specified by setting the <tt class="member">restype</tt> attribute of
the function object.

<p>
Here is a more advanced example, it uses the <code>strchr</code> function, which
expects a string pointer and a char, and returns a pointer to a
string:
<div class="verbatim"><pre>
&gt;&gt;&gt; strchr = libc.strchr
&gt;&gt;&gt; strchr("abcdef", ord("d")) # doctest: +SKIP
8059983
&gt;&gt;&gt; strchr.restype = c_char_p # c_char_p is a pointer to a string
&gt;&gt;&gt; strchr("abcdef", ord("d"))
'def'
&gt;&gt;&gt; print strchr("abcdef", ord("x"))
None
&gt;&gt;&gt;
</pre></div>

<p>
If you want to avoid the <code>ord("x")</code> calls above, you can set the
<tt class="member">argtypes</tt> attribute, and the second argument will be converted from
a single character Python string into a C char:
<div class="verbatim"><pre>
&gt;&gt;&gt; strchr.restype = c_char_p
&gt;&gt;&gt; strchr.argtypes = [c_char_p, c_char]
&gt;&gt;&gt; strchr("abcdef", "d")
'def'
&gt;&gt;&gt; strchr("abcdef", "def")
Traceback (most recent call last):
  File "&lt;stdin&gt;", line 1, in ?
ArgumentError: argument 2: exceptions.TypeError: one character string expected
&gt;&gt;&gt; print strchr("abcdef", "x")
None
&gt;&gt;&gt; strchr("abcdef", "d")
'def'
&gt;&gt;&gt;
</pre></div>

<p>
You can also use a callable Python object (a function or a class for
example) as the <tt class="member">restype</tt> attribute, if the foreign function returns
an integer.  The callable will be called with the <code>integer</code> the C
function returns, and the result of this call will be used as the
result of your function call. This is useful to check for error return
values and automatically raise an exception:
<div class="verbatim"><pre>
&gt;&gt;&gt; GetModuleHandle = windll.kernel32.GetModuleHandleA # doctest: +WINDOWS
&gt;&gt;&gt; def ValidHandle(value):
...     if value == 0:
...         raise WinError()
...     return value
...
&gt;&gt;&gt;
&gt;&gt;&gt; GetModuleHandle.restype = ValidHandle # doctest: +WINDOWS
&gt;&gt;&gt; GetModuleHandle(None) # doctest: +WINDOWS
486539264
&gt;&gt;&gt; GetModuleHandle("something silly") # doctest: +WINDOWS
Traceback (most recent call last):
  File "&lt;stdin&gt;", line 1, in ?
  File "&lt;stdin&gt;", line 3, in ValidHandle
WindowsError: [Errno 126] The specified module could not be found.
&gt;&gt;&gt;
</pre></div>

<p>
<code>WinError</code> is a function which will call Windows <code>FormatMessage()</code>
api to get the string representation of an error code, and <em>returns</em>
an exception.  <code>WinError</code> takes an optional error code parameter, if
no one is used, it calls <tt class="function">GetLastError()</tt> to retrieve it.

<p>
Please note that a much more powerful error checking mechanism is
available through the <tt class="member">errcheck</tt> attribute; see the reference manual
for details.

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="14.14.1.7 specifying the required"
  href="ctypes-specifying-required-argument-types.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="14.14.1 ctypes tutorial"
  href="ctypes-ctypes-tutorial.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="14.14.1.9 passing pointers (or:"
  href="ctypes-passing-pointers.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="ctypes-specifying-required-argument-types.html">14.14.1.7 Specifying the required</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="ctypes-ctypes-tutorial.html">14.14.1 ctypes tutorial</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="ctypes-passing-pointers.html">14.14.1.9 Passing pointers (or:</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
